# -*- coding: utf-8 -*-
"""
permission.py —— WMS 应用的权限判定接口

用途：
- 为 hooks.py 中 add_to_apps_screen 的 "has_permission" 提供入口函数，
  控制“应用中心（Apps Screen）”是否显示/允许访问 WMS 应用。

设计原则：
- 以角色（Role）为基础进行快速判定，避免复杂的数据库查询。
- 支持传入指定用户 ID 或默认使用当前会话用户。
- 保持轻量、无副作用。

使用说明：
- 在 hooks.py 中以 "wms.api.permission.has_app_permission" 引用本函数。
- 当函数返回 True 时，Apps 页面显示并允许访问 WMS；返回 False 则隐藏或禁用。
"""

import frappe

def has_app_permission(user=None):
    """
    检查用户是否有 WMS 应用权限

    参数:
        user (str | None): 用户 ID，可为空；为空时默认读取当前会话用户。

    返回:
        bool: 是否具备访问 WMS 应用的权限。

    判定逻辑：
    - 获取用户的角色集合（frappe.get_roles）
    - 与允许访问的角色集合进行交集判定，有任一匹配则返回 True

    允许访问角色示例：
    - System Manager：系统管理员，具备全局管理权限
    - WMS Manager：仓储系统管理员或高级用户
    - Warehouse User：仓库操作员，执行入库/出库等操作
    - Stock User：库存管理相关角色

    注意事项：
    - 角色名称需与系统中定义的 Role 保持一致，否则判定将失败。
    - 若需要更细粒度的权限控制，可扩展为基于用户权限（Permission）或设置项的判定。
    """
    roles = frappe.get_roles(user) if user else frappe.get_roles()
    allowed_roles = ['System Manager', 'WMS Manager', 'Warehouse User', 'Stock User']
    return any(role in allowed_roles for role in roles)